home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 98 / Skunkware 98.iso / src / interp / perl5.005.tar.gz / perl5.005.tar / perl5.005 / pod / perldebug.pod < prev    next >
Text File  |  1998-07-11  |  55KB  |  1,662 lines
  1. =head1 NAME
  2.  
  3. perldebug - Perl debugging
  4.  
  5. =head1 DESCRIPTION
  6.  
  7. First of all, have you tried using the B<-w> switch?
  8.  
  9. =head1 The Perl Debugger
  10.  
  11. "As soon as we started programming, we found to our
  12. surprise that it wasn't as easy to get programs right
  13. as we had thought.  Debugging had to be discovered.
  14. I can remember the exact instant when I realized that
  15. a large part of my life from then on was going to be
  16. spent in finding mistakes in my own programs."
  17.  
  18. I<  --Maurice Wilkes, 1949>
  19.  
  20. If you invoke Perl with the B<-d> switch, your script runs under the
  21. Perl source debugger.  This works like an interactive Perl
  22. environment, prompting for debugger commands that let you examine
  23. source code, set breakpoints, get stack backtraces, change the values of
  24. variables, etc.  This is so convenient that you often fire up
  25. the debugger all by itself just to test out Perl constructs
  26. interactively to see what they do.  For example:
  27.  
  28.     perl -d -e 42
  29.  
  30. In Perl, the debugger is not a separate program as it usually is in the
  31. typical compiled environment.  Instead, the B<-d> flag tells the compiler
  32. to insert source information into the parse trees it's about to hand off
  33. to the interpreter.  That means your code must first compile correctly
  34. for the debugger to work on it.  Then when the interpreter starts up, it
  35. preloads a Perl library file containing the debugger itself.
  36.  
  37. The program will halt I<right before> the first run-time executable
  38. statement (but see below regarding compile-time statements) and ask you
  39. to enter a debugger command.  Contrary to popular expectations, whenever
  40. the debugger halts and shows you a line of code, it always displays the
  41. line it's I<about> to execute, rather than the one it has just executed.
  42.  
  43. Any command not recognized by the debugger is directly executed
  44. (C<eval>'d) as Perl code in the current package.  (The debugger uses the
  45. DB package for its own state information.)
  46.  
  47. Leading white space before a command would cause the debugger to think
  48. it's I<NOT> a debugger command but for Perl, so be careful not to do
  49. that.
  50.  
  51. =head2 Debugger Commands
  52.  
  53. The debugger understands the following commands:
  54.  
  55. =over 12
  56.  
  57. =item h [command]
  58.  
  59. Prints out a help message.
  60.  
  61. If you supply another debugger command as an argument to the C<h> command,
  62. it prints out the description for just that command.  The special
  63. argument of C<h h> produces a more compact help listing, designed to fit
  64. together on one screen.
  65.  
  66. If the output of the C<h> command (or any command, for that matter) scrolls
  67. past your screen, either precede the command with a leading pipe symbol so
  68. it's run through your pager, as in
  69.  
  70.     DB> |h
  71.  
  72. You may change the pager which is used via C<O pager=...> command.
  73.  
  74. =item p expr
  75.  
  76. Same as C<print {$DB::OUT} expr> in the current package.  In particular,
  77. because this is just Perl's own B<print> function, this means that nested
  78. data structures and objects are not dumped, unlike with the C<x> command.
  79.  
  80. The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of
  81. where STDOUT may be redirected to.
  82.  
  83. =item x expr
  84.  
  85. Evaluates its expression in list context and dumps out the result
  86. in a pretty-printed fashion.  Nested data structures are printed out
  87. recursively, unlike the C<print> function.
  88.  
  89. The details of printout are governed by multiple C<O>ptions.
  90.  
  91. =item V [pkg [vars]]
  92.  
  93. Display all (or some) variables in package (defaulting to the C<main>
  94. package) using a data pretty-printer (hashes show their keys and values so
  95. you see what's what, control characters are made printable, etc.).  Make
  96. sure you don't put the type specifier (like C<$>) there, just the symbol
  97. names, like this:
  98.  
  99.     V DB filename line
  100.  
  101. Use C<~pattern> and C<!pattern> for positive and negative regexps.
  102.  
  103. Nested data structures are printed out in a legible fashion, unlike
  104. the C<print> function.
  105.  
  106. The details of printout are governed by multiple C<O>ptions.
  107.  
  108. =item X [vars]
  109.  
  110. Same as C<V currentpackage [vars]>.
  111.  
  112. =item T
  113.  
  114. Produce a stack backtrace.  See below for details on its output.
  115.  
  116. =item s [expr]
  117.  
  118. Single step.  Executes until it reaches the beginning of another
  119. statement, descending into subroutine calls.  If an expression is
  120. supplied that includes function calls, it too will be single-stepped.
  121.  
  122. =item n [expr]
  123.  
  124. Next.  Executes over subroutine calls, until it reaches the beginning
  125. of the next statement.  If an expression is supplied that includes
  126. function calls, those functions will be executed with stops before
  127. each statement.
  128.  
  129. =item E<lt>CRE<gt>
  130.  
  131. Repeat last C<n> or C<s> command.
  132.  
  133. =item c [line|sub]
  134.  
  135. Continue, optionally inserting a one-time-only breakpoint
  136. at the specified line or subroutine.
  137.  
  138. =item l
  139.  
  140. List next window of lines.
  141.  
  142. =item l min+incr
  143.  
  144. List C<incr+1> lines starting at C<min>.
  145.  
  146. =item l min-max
  147.  
  148. List lines C<min> through C<max>.  C<l -> is synonymous to C<->.
  149.  
  150. =item l line
  151.  
  152. List a single line.
  153.  
  154. =item l subname
  155.  
  156. List first window of lines from subroutine.
  157.  
  158. =item -
  159.  
  160. List previous window of lines.
  161.  
  162. =item w [line]
  163.  
  164. List window (a few lines) around the current line.
  165.  
  166. =item .
  167.  
  168. Return debugger pointer to the last-executed line and
  169. print it out.
  170.  
  171. =item f filename
  172.  
  173. Switch to viewing a different file or eval statement.  If C<filename>
  174. is not a full filename as found in values of %INC, it is considered as
  175. a regexp.
  176.  
  177. =item /pattern/
  178.  
  179. Search forwards for pattern; final / is optional.
  180.  
  181. =item ?pattern?
  182.  
  183. Search backwards for pattern; final ? is optional.
  184.  
  185. =item L
  186.  
  187. List all breakpoints and actions.
  188.  
  189. =item S [[!]pattern]
  190.  
  191. List subroutine names [not] matching pattern.
  192.  
  193. =item t
  194.  
  195. Toggle trace mode (see also C<AutoTrace> C<O>ption).
  196.  
  197. =item t expr
  198.  
  199. Trace through execution of expr.  For example:
  200.  
  201.  $ perl -de 42
  202.  Stack dump during die enabled outside of evals.
  203.  
  204.  Loading DB routines from perl5db.pl patch level 0.94
  205.  Emacs support available.
  206.  
  207.  Enter h or `h h' for help.
  208.  
  209.  main::(-e:1):   0
  210.    DB<1> sub foo { 14 }
  211.  
  212.    DB<2> sub bar { 3 }
  213.  
  214.    DB<3> t print foo() * bar()
  215.  main::((eval 172):3):   print foo() + bar();
  216.  main::foo((eval 168):2):
  217.  main::bar((eval 170):2):
  218.  42
  219.  
  220. or, with the C<O>ption C<frame=2> set,
  221.  
  222.    DB<4> O f=2
  223.                 frame = '2'
  224.    DB<5> t print foo() * bar()
  225.  3:      foo() * bar()
  226.  entering main::foo
  227.   2:     sub foo { 14 };
  228.  exited main::foo
  229.  entering main::bar
  230.   2:     sub bar { 3 };
  231.  exited main::bar
  232.  42
  233.  
  234. =item b [line] [condition]
  235.  
  236. Set a breakpoint.  If line is omitted, sets a breakpoint on the line
  237. that is about to be executed.  If a condition is specified, it's
  238. evaluated each time the statement is reached and a breakpoint is taken
  239. only if the condition is true.  Breakpoints may be set on only lines
  240. that begin an executable statement.  Conditions don't use B<if>:
  241.  
  242.     b 237 $x > 30
  243.     b 237 ++$count237 < 11
  244.     b 33 /pattern/i
  245.  
  246. =item b subname [condition]
  247.  
  248. Set a breakpoint at the first line of the named subroutine.
  249.  
  250. =item b postpone subname [condition]
  251.  
  252. Set breakpoint at first line of subroutine after it is compiled.
  253.  
  254. =item b load filename
  255.  
  256. Set breakpoint at the first executed line of the file.  Filename should
  257. be a full name as found in values of %INC.
  258.  
  259. =item b compile subname
  260.  
  261. Sets breakpoint at the first statement executed after the subroutine
  262. is compiled.
  263.  
  264. =item d [line]
  265.  
  266. Delete a breakpoint at the specified line.  If line is omitted, deletes
  267. the breakpoint on the line that is about to be executed.
  268.  
  269. =item D
  270.  
  271. Delete all installed breakpoints.
  272.  
  273. =item a [line] command
  274.  
  275. Set an action to be done before the line is executed.
  276. The sequence of steps taken by the debugger is
  277.  
  278.   1. check for a breakpoint at this line
  279.   2. print the line if necessary (tracing)
  280.   3. do any actions associated with that line
  281.   4. prompt user if at a breakpoint or in single-step
  282.   5. evaluate line
  283.  
  284. For example, this will print out $foo every time line
  285. 53 is passed:
  286.  
  287.     a 53 print "DB FOUND $foo\n"
  288.  
  289. =item A
  290.  
  291. Delete all installed actions.
  292.  
  293. =item W [expr]
  294.  
  295. Add a global watch-expression.
  296.  
  297. =item W
  298.  
  299. Delete all watch-expressions.
  300.  
  301. =item O [opt[=val]] [opt"val"] [opt?]...
  302.  
  303. Set or query values of options.  val defaults to 1.  opt can
  304. be abbreviated.  Several options can be listed.
  305.  
  306. =over 12
  307.  
  308. =item C<recallCommand>, C<ShellBang>
  309.  
  310. The characters used to recall command or spawn shell.  By
  311. default, these are both set to C<!>.
  312.  
  313. =item C<pager>
  314.  
  315. Program to use for output of pager-piped commands (those
  316. beginning with a C<|> character.)  By default,
  317. C<$ENV{PAGER}> will be used.
  318.  
  319. =item C<tkRunning>
  320.  
  321. Run Tk while prompting (with ReadLine).
  322.  
  323. =item C<signalLevel>, C<warnLevel>, C<dieLevel>
  324.  
  325. Level of verbosity.  By default the debugger is in a sane verbose mode,
  326. thus it will print backtraces on all the warnings and die-messages
  327. which are going to be printed out, and will print a message when
  328. interesting uncaught signals arrive.
  329.  
  330. To disable this behaviour, set these values to 0.  If C<dieLevel> is 2,
  331. then the messages which will be caught by surrounding C<eval> are also
  332. printed.
  333.  
  334. =item C<AutoTrace>
  335.  
  336. Trace mode (similar to C<t> command, but can be put into
  337. C<PERLDB_OPTS>).
  338.  
  339. =item C<LineInfo>
  340.  
  341. File or pipe to print line number info to.  If it is a pipe (say,
  342. C<|visual_perl_db>), then a short, "emacs like" message is used.
  343.  
  344. =item C<inhibit_exit>
  345.  
  346. If 0, allows I<stepping off> the end of the script.
  347.  
  348. =item C<PrintRet>
  349.  
  350. affects printing of return value after C<r> command.
  351.  
  352. =item C<ornaments>
  353.  
  354. affects screen appearance of the command line (see L<Term::ReadLine>).
  355.  
  356. =item C<frame>
  357.  
  358. affects printing messages on entry and exit from subroutines.  If
  359. C<frame & 2> is false, messages are printed on entry only. (Printing
  360. on exit may be useful if inter(di)spersed with other messages.)
  361.  
  362. If C<frame & 4>, arguments to functions are printed as well as the
  363. context and caller info.  If C<frame & 8>, overloaded C<stringify> and
  364. C<tie>d C<FETCH> are enabled on the printed arguments. If C<frame &
  365. 16>, the return value from the subroutine is printed as well.
  366.  
  367. The length at which the argument list is truncated is governed by the
  368. next option:
  369.  
  370. =item C<maxTraceLen>
  371.  
  372. length at which the argument list is truncated when C<frame> option's
  373. bit 4 is set.
  374.  
  375. =back
  376.  
  377. The following options affect what happens with C<V>, C<X>, and C<x>
  378. commands:
  379.  
  380. =over 12
  381.  
  382. =item C<arrayDepth>, C<hashDepth>
  383.  
  384. Print only first N elements ('' for all).
  385.  
  386. =item C<compactDump>, C<veryCompact>
  387.  
  388. Change style of array and hash dump.  If C<compactDump>, short array
  389. may be printed on one line.
  390.  
  391. =item C<globPrint>
  392.  
  393. Whether to print contents of globs.
  394.  
  395. =item C<DumpDBFiles>
  396.  
  397. Dump arrays holding debugged files.
  398.  
  399. =item C<DumpPackages>
  400.  
  401. Dump symbol tables of packages.
  402.  
  403. =item C<DumpReused>
  404.  
  405. Dump contents of "reused" addresses.
  406.  
  407. =item C<quote>, C<HighBit>, C<undefPrint>
  408.  
  409. Change style of string dump.  Default value of C<quote> is C<auto>, one
  410. can enable either double-quotish dump, or single-quotish by setting it
  411. to C<"> or C<'>.  By default, characters with high bit set are printed
  412. I<as is>.
  413.  
  414. =item C<UsageOnly>
  415.  
  416. I<very> rudimentally per-package memory usage dump.  Calculates total
  417. size of strings in variables in the package.
  418.  
  419. =back
  420.  
  421. During startup options are initialized from C<$ENV{PERLDB_OPTS}>.
  422. You can put additional initialization options C<TTY>, C<noTTY>,
  423. C<ReadLine>, and C<NonStop> there.
  424.  
  425. Example rc file:
  426.  
  427.   &parse_options("NonStop=1 LineInfo=db.out AutoTrace");
  428.  
  429. The script will run without human intervention, putting trace information
  430. into the file I<db.out>.  (If you interrupt it, you would better reset
  431. C<LineInfo> to something "interactive"!)
  432.  
  433. =over 12
  434.  
  435. =item C<TTY>
  436.  
  437. The TTY to use for debugging I/O.
  438.  
  439. =item C<noTTY>
  440.  
  441. If set, goes in C<NonStop> mode, and would not connect to a TTY.  If
  442. interrupt (or if control goes to debugger via explicit setting of
  443. $DB::signal or $DB::single from the Perl script), connects to a TTY
  444. specified by the C<TTY> option at startup, or to a TTY found at
  445. runtime using C<Term::Rendezvous> module of your choice.
  446.  
  447. This module should implement a method C<new> which returns an object
  448. with two methods: C<IN> and C<OUT>, returning two filehandles to use
  449. for debugging input and output correspondingly.  Method C<new> may
  450. inspect an argument which is a value of C<$ENV{PERLDB_NOTTY}> at
  451. startup, or is C<"/tmp/perldbtty$$"> otherwise.
  452.  
  453. =item C<ReadLine>
  454.  
  455. If false, readline support in debugger is disabled, so you can debug
  456. ReadLine applications.
  457.  
  458. =item C<NonStop>
  459.  
  460. If set, debugger goes into noninteractive mode until interrupted, or
  461. programmatically by setting $DB::signal or $DB::single.
  462.  
  463. =back
  464.  
  465. Here's an example of using the C<$ENV{PERLDB_OPTS}> variable:
  466.  
  467.   $ PERLDB_OPTS="N f=2" perl -d myprogram
  468.  
  469. will run the script C<myprogram> without human intervention, printing
  470. out the call tree with entry and exit points.  Note that C<N f=2> is
  471. equivalent to C<NonStop=1 frame=2>.  Note also that at the moment when
  472. this documentation was written all the options to the debugger could
  473. be uniquely abbreviated by the first letter (with exception of
  474. C<Dump*> options).
  475.  
  476. Other examples may include
  477.  
  478.   $ PERLDB_OPTS="N f A L=listing" perl -d myprogram
  479.  
  480. - runs script noninteractively, printing info on each entry into a
  481. subroutine and each executed line into the file F<listing>. (If you
  482. interrupt it, you would better reset C<LineInfo> to something
  483. "interactive"!)
  484.  
  485.  
  486.   $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram
  487.  
  488. may be useful for debugging a program which uses C<Term::ReadLine>
  489. itself.  Do not forget detach shell from the TTY in the window which
  490. corresponds to F</dev/ttyc>, say, by issuing a command like
  491.  
  492.   $ sleep 1000000
  493.  
  494. See L<"Debugger Internals"> below for more details.
  495.  
  496. =item E<lt> [ command ]
  497.  
  498. Set an action (Perl command) to happen before every debugger prompt.
  499. A multi-line command may be entered by backslashing the newlines.  If
  500. C<command> is missing, resets the list of actions.
  501.  
  502. =item E<lt>E<lt> command
  503.  
  504. Add an action (Perl command) to happen before every debugger prompt.
  505. A multi-line command may be entered by backslashing the newlines.
  506.  
  507. =item E<gt> command
  508.  
  509. Set an action (Perl command) to happen after the prompt when you've
  510. just given a command to return to executing the script.  A multi-line
  511. command may be entered by backslashing the newlines.  If C<command> is
  512. missing, resets the list of actions.
  513.  
  514. =item E<gt>E<gt> command
  515.  
  516. Adds an action (Perl command) to happen after the prompt when you've
  517. just given a command to return to executing the script.  A multi-line
  518. command may be entered by backslashing the newlines.
  519.  
  520. =item { [ command ]
  521.  
  522. Set an action (debugger command) to happen before every debugger prompt.
  523. A multi-line command may be entered by backslashing the newlines.  If
  524. C<command> is missing, resets the list of actions.
  525.  
  526. =item {{ command
  527.  
  528. Add an action (debugger command) to happen before every debugger prompt.
  529. A multi-line command may be entered by backslashing the newlines.
  530.  
  531. =item ! number
  532.  
  533. Redo a previous command (default previous command).
  534.  
  535. =item ! -number
  536.  
  537. Redo number'th-to-last command.
  538.  
  539. =item ! pattern
  540.  
  541. Redo last command that started with pattern.
  542. See C<O recallCommand>, too.
  543.  
  544. =item !! cmd
  545.  
  546. Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT)
  547. See C<O shellBang> too.
  548.  
  549. =item H -number
  550.  
  551. Display last n commands.  Only commands longer than one character are
  552. listed.  If number is omitted, lists them all.
  553.  
  554. =item q or ^D
  555.  
  556. Quit.  ("quit" doesn't work for this.)  This is the only supported way
  557. to exit the debugger, though typing C<exit> twice may do it too.
  558.  
  559. Set an C<O>ption C<inhibit_exit> to 0 if you want to be able to I<step
  560. off> the end the script.  You may also need to set C<$finished> to 0 at
  561. some moment if you want to step through global destruction.
  562.  
  563. =item R
  564.  
  565. Restart the debugger by B<exec>ing a new session.  It tries to maintain
  566. your history across this, but internal settings and command line options
  567. may be lost.
  568.  
  569. Currently the following setting are preserved: history, breakpoints,
  570. actions, debugger C<O>ptions, and the following command line
  571. options: B<-w>, B<-I>, and B<-e>.
  572.  
  573. =item |dbcmd
  574.  
  575. Run debugger command, piping DB::OUT to current pager.
  576.  
  577. =item ||dbcmd
  578.  
  579. Same as C<|dbcmd> but DB::OUT is temporarily B<select>ed as well.
  580. Often used with commands that would otherwise produce long
  581. output, such as
  582.  
  583.     |V main
  584.  
  585. =item = [alias value]
  586.  
  587. Define a command alias, like
  588.  
  589.     = quit q
  590.  
  591. or list current aliases.
  592.  
  593. =item command
  594.  
  595. Execute command as a Perl statement.  A missing semicolon will be
  596. supplied.
  597.  
  598. =item m expr
  599.  
  600. The expression is evaluated, and the methods which may be applied to
  601. the result are listed.
  602.  
  603. =item m package
  604.  
  605. The methods which may be applied to objects in the C<package> are listed.
  606.  
  607. =back
  608.  
  609. =head2 Debugger input/output
  610.  
  611. =over 8
  612.  
  613. =item Prompt
  614.  
  615. The debugger prompt is something like
  616.  
  617.     DB<8>
  618.  
  619. or even
  620.  
  621.     DB<<17>>
  622.  
  623. where that number is the command number, which you'd use to access with
  624. the builtin B<csh>-like history mechanism, e.g., C<!17> would repeat
  625. command number 17.  The number of angle brackets indicates the depth of
  626. the debugger.  You could get more than one set of brackets, for example, if
  627. you'd already at a breakpoint and then printed out the result of a
  628. function call that itself also has a breakpoint, or you step into an
  629. expression via C<s/n/t expression> command.
  630.  
  631. =item Multiline commands
  632.  
  633. If you want to enter a multi-line command, such as a subroutine
  634. definition with several statements, or a format, you may escape the
  635. newline that would normally end the debugger command with a backslash.
  636. Here's an example:
  637.  
  638.       DB<1> for (1..4) {         \
  639.       cont:     print "ok\n";   \
  640.       cont: }
  641.       ok
  642.       ok
  643.       ok
  644.       ok
  645.  
  646. Note that this business of escaping a newline is specific to interactive
  647. commands typed into the debugger.
  648.  
  649. =item Stack backtrace
  650.  
  651. Here's an example of what a stack backtrace via C<T> command might
  652. look like:
  653.  
  654.     $ = main::infested called from file `Ambulation.pm' line 10
  655.     @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
  656.     $ = main::pests('bactrian', 4) called from file `camel_flea' line 4
  657.  
  658. The left-hand character up there tells whether the function was called
  659. in a scalar or list context (we bet you can tell which is which).  What
  660. that says is that you were in the function C<main::infested> when you ran
  661. the stack dump, and that it was called in a scalar context from line 10
  662. of the file I<Ambulation.pm>, but without any arguments at all, meaning
  663. it was called as C<&infested>.  The next stack frame shows that the
  664. function C<Ambulation::legs> was called in a list context from the
  665. I<camel_flea> file with four arguments.  The last stack frame shows that
  666. C<main::pests> was called in a scalar context, also from I<camel_flea>,
  667. but from line 4.
  668.  
  669. Note that if you execute C<T> command from inside an active C<use>
  670. statement, the backtrace will contain both C<require>
  671. frame and an C<eval>) frame.
  672.  
  673. =item Listing
  674.  
  675. Listing given via different flavors of C<l> command looks like this:
  676.  
  677.     DB<<13>> l
  678.   101:                @i{@i} = ();
  679.   102:b               @isa{@i,$pack} = ()
  680.   103                     if(exists $i{$prevpack} || exists $isa{$pack});
  681.   104             }
  682.   105
  683.   106             next
  684.   107==>              if(exists $isa{$pack});
  685.   108
  686.   109:a           if ($extra-- > 0) {
  687.   110:                %isa = ($pack,1);
  688.  
  689. Note that the breakable lines are marked with C<:>, lines with
  690. breakpoints are marked by C<b>, with actions by C<a>, and the
  691. next executed line is marked by C<==E<gt>>.
  692.  
  693. =item Frame listing
  694.  
  695. When C<frame> option is set, debugger would print entered (and
  696. optionally exited) subroutines in different styles.
  697.  
  698. What follows is the start of the listing of
  699.  
  700.   env "PERLDB_OPTS=f=n N" perl -d -V
  701.  
  702. for different values of C<n>:
  703.  
  704. =over 4
  705.  
  706. =item 1
  707.  
  708.   entering main::BEGIN
  709.    entering Config::BEGIN
  710.     Package lib/Exporter.pm.
  711.     Package lib/Carp.pm.
  712.    Package lib/Config.pm.
  713.    entering Config::TIEHASH
  714.    entering Exporter::import
  715.     entering Exporter::export
  716.   entering Config::myconfig
  717.    entering Config::FETCH
  718.    entering Config::FETCH
  719.    entering Config::FETCH
  720.    entering Config::FETCH
  721.  
  722. =item 2
  723.  
  724.   entering main::BEGIN
  725.    entering Config::BEGIN
  726.     Package lib/Exporter.pm.
  727.     Package lib/Carp.pm.
  728.    exited Config::BEGIN
  729.    Package lib/Config.pm.
  730.    entering Config::TIEHASH
  731.    exited Config::TIEHASH
  732.    entering Exporter::import
  733.     entering Exporter::export
  734.     exited Exporter::export
  735.    exited Exporter::import
  736.   exited main::BEGIN
  737.   entering Config::myconfig
  738.    entering Config::FETCH
  739.    exited Config::FETCH
  740.    entering Config::FETCH
  741.    exited Config::FETCH
  742.    entering Config::FETCH
  743.  
  744. =item 4
  745.  
  746.   in  $=main::BEGIN() from /dev/nul:0
  747.    in  $=Config::BEGIN() from lib/Config.pm:2
  748.     Package lib/Exporter.pm.
  749.     Package lib/Carp.pm.
  750.    Package lib/Config.pm.
  751.    in  $=Config::TIEHASH('Config') from lib/Config.pm:644
  752.    in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
  753.     in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li
  754.   in  @=Config::myconfig() from /dev/nul:0
  755.    in  $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
  756.    in  $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
  757.    in  $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574
  758.    in  $=Config::FETCH(ref(Config), 'SUBVERSION') from lib/Config.pm:574
  759.    in  $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574
  760.    in  $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574
  761.  
  762. =item 6
  763.  
  764.   in  $=main::BEGIN() from /dev/nul:0
  765.    in  $=Config::BEGIN() from lib/Config.pm:2
  766.     Package lib/Exporter.pm.
  767.     Package lib/Carp.pm.
  768.    out $=Config::BEGIN() from lib/Config.pm:0
  769.    Package lib/Config.pm.
  770.    in  $=Config::TIEHASH('Config') from lib/Config.pm:644
  771.    out $=Config::TIEHASH('Config') from lib/Config.pm:644
  772.    in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
  773.     in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
  774.     out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
  775.    out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
  776.   out $=main::BEGIN() from /dev/nul:0
  777.   in  @=Config::myconfig() from /dev/nul:0
  778.    in  $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
  779.    out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
  780.    in  $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
  781.    out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
  782.    in  $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574
  783.    out $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574
  784.    in  $=Config::FETCH(ref(Config), 'SUBVERSION') from lib/Config.pm:574
  785.  
  786. =item 14
  787.  
  788.   in  $=main::BEGIN() from /dev/nul:0
  789.    in  $=Config::BEGIN() from lib/Config.pm:2
  790.     Package lib/Exporter.pm.
  791.     Package lib/Carp.pm.
  792.    out $=Config::BEGIN() from lib/Config.pm:0
  793.    Package lib/Config.pm.
  794.    in  $=Config::TIEHASH('Config') from lib/Config.pm:644
  795.    out $=Config::TIEHASH('Config') from lib/Config.pm:644
  796.    in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
  797.     in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
  798.     out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
  799.    out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
  800.   out $=main::BEGIN() from /dev/nul:0
  801.   in  @=Config::myconfig() from /dev/nul:0
  802.    in  $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
  803.    out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
  804.    in  $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
  805.    out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
  806.  
  807. =item 30
  808.  
  809.   in  $=CODE(0x15eca4)() from /dev/null:0
  810.    in  $=CODE(0x182528)() from lib/Config.pm:2
  811.     Package lib/Exporter.pm.
  812.    out $=CODE(0x182528)() from lib/Config.pm:0
  813.    scalar context return from CODE(0x182528): undef
  814.    Package lib/Config.pm.
  815.    in  $=Config::TIEHASH('Config') from lib/Config.pm:628
  816.    out $=Config::TIEHASH('Config') from lib/Config.pm:628
  817.    scalar context return from Config::TIEHASH:   empty hash
  818.    in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
  819.     in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
  820.     out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
  821.     scalar context return from Exporter::export: ''
  822.    out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
  823.    scalar context return from Exporter::import: ''
  824.  
  825.  
  826. =back
  827.  
  828. In all the cases indentation of lines shows the call tree, if bit 2 of
  829. C<frame> is set, then a line is printed on exit from a subroutine as
  830. well, if bit 4 is set, then the arguments are printed as well as the
  831. caller info, if bit 8 is set, the arguments are printed even if they
  832. are tied or references, if bit 16 is set, the return value is printed
  833. as well.
  834.  
  835. When a package is compiled, a line like this
  836.  
  837.     Package lib/Carp.pm.
  838.  
  839. is printed with proper indentation.
  840.  
  841. =back
  842.  
  843. =head2 Debugging compile-time statements
  844.  
  845. If you have any compile-time executable statements (code within a BEGIN
  846. block or a C<use> statement), these will C<NOT> be stopped by debugger,
  847. although C<require>s will (and compile-time statements can be traced
  848. with C<AutoTrace> option set in C<PERLDB_OPTS>).  From your own Perl
  849. code, however, you can
  850. transfer control back to the debugger using the following statement,
  851. which is harmless if the debugger is not running:
  852.  
  853.     $DB::single = 1;
  854.  
  855. If you set C<$DB::single> to the value 2, it's equivalent to having
  856. just typed the C<n> command, whereas a value of 1 means the C<s>
  857. command.  The C<$DB::trace>  variable should be set to 1 to simulate
  858. having typed the C<t> command.
  859.  
  860. Another way to debug compile-time code is to start debugger, set a
  861. breakpoint on I<load> of some module thusly
  862.  
  863.     DB<7> b load f:/perllib/lib/Carp.pm
  864.   Will stop on load of `f:/perllib/lib/Carp.pm'.
  865.  
  866. and restart debugger by C<R> command (if possible).  One can use C<b
  867. compile subname> for the same purpose.
  868.  
  869. =head2 Debugger Customization
  870.  
  871. Most probably you do not want to modify the debugger, it contains enough
  872. hooks to satisfy most needs.  You may change the behaviour of debugger
  873. from the debugger itself, using C<O>ptions, from the command line via
  874. C<PERLDB_OPTS> environment variable, and from I<customization files>.
  875.  
  876. You can do some customization by setting up a F<.perldb> file which
  877. contains initialization code.  For instance, you could make aliases
  878. like these (the last one is one people expect to be there):
  879.  
  880.     $DB::alias{'len'}  = 's/^len(.*)/p length($1)/';
  881.     $DB::alias{'stop'} = 's/^stop (at|in)/b/';
  882.     $DB::alias{'ps'}   = 's/^ps\b/p scalar /';
  883.     $DB::alias{'quit'} = 's/^quit(\s*)/exit\$/';
  884.  
  885. One changes options from F<.perldb> file via calls like this one;
  886.  
  887.     parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2");
  888.  
  889. (the code is executed in the package C<DB>).  Note that F<.perldb> is
  890. processed before processing C<PERLDB_OPTS>.  If F<.perldb> defines the
  891. subroutine C<afterinit>, it is called after all the debugger
  892. initialization ends.  F<.perldb> may be contained in the current
  893. directory, or in the C<LOGDIR>/C<HOME> directory.
  894.  
  895. If you want to modify the debugger, copy F<perl5db.pl> from the Perl
  896. library to another name and modify it as necessary.  You'll also want
  897. to set your C<PERL5DB> environment variable to say something like this:
  898.  
  899.     BEGIN { require "myperl5db.pl" }
  900.  
  901. As the last resort, one can use C<PERL5DB> to customize debugger by
  902. directly setting internal variables or calling debugger functions.
  903.  
  904. =head2 Readline Support
  905.  
  906. As shipped, the only command line history supplied is a simplistic one
  907. that checks for leading exclamation points.  However, if you install
  908. the Term::ReadKey and Term::ReadLine modules from CPAN, you will
  909. have full editing capabilities much like GNU I<readline>(3) provides.
  910. Look for these in the F<modules/by-module/Term> directory on CPAN.
  911.  
  912. A rudimentary command line completion is also available.
  913. Unfortunately, the names of lexical variables are not available for
  914. completion.
  915.  
  916. =head2 Editor Support for Debugging
  917.  
  918. If you have GNU B<emacs> installed on your system, it can interact with
  919. the Perl debugger to provide an integrated software development
  920. environment reminiscent of its interactions with C debuggers.
  921.  
  922. Perl is also delivered with a start file for making B<emacs> act like a
  923. syntax-directed editor that understands (some of) Perl's syntax.  Look in
  924. the I<emacs> directory of the Perl source distribution.
  925.  
  926. (Historically, a similar setup for interacting with B<vi> and the
  927. X11 window system had also been available, but at the time of this
  928. writing, no debugger support for B<vi> currently exists.)
  929.  
  930. =head2 The Perl Profiler
  931.  
  932. If you wish to supply an alternative debugger for Perl to run, just
  933. invoke your script with a colon and a package argument given to the B<-d>
  934. flag.  One of the most popular alternative debuggers for Perl is
  935. B<DProf>, the Perl profiler.   As of this writing, B<DProf> is not
  936. included with the standard Perl distribution, but it is expected to
  937. be included soon, for certain values of "soon".
  938.  
  939. Meanwhile, you can fetch the Devel::Dprof module from CPAN.  Assuming
  940. it's properly installed on your system, to profile your Perl program in
  941. the file F<mycode.pl>, just type:
  942.  
  943.     perl -d:DProf mycode.pl
  944.  
  945. When the script terminates the profiler will dump the profile information
  946. to a file called F<tmon.out>.  A tool like B<dprofpp> (also supplied with
  947. the Devel::DProf package) can be used to interpret the information which is
  948. in that profile.
  949.  
  950. =head2 Debugger support in perl
  951.  
  952. When you call the B<caller> function (see L<perlfunc/caller>) from the
  953. package DB, Perl sets the array @DB::args to contain the arguments the
  954. corresponding stack frame was called with.
  955.  
  956. If perl is run with B<-d> option, the following additional features
  957. are enabled (cf. L<perlvar/$^P>):
  958.  
  959. =over
  960.  
  961. =item *
  962.  
  963. Perl inserts the contents of C<$ENV{PERL5DB}> (or C<BEGIN {require
  964. 'perl5db.pl'}> if not present) before the first line of the
  965. application.
  966.  
  967. =item *
  968.  
  969. The array C<@{"_E<lt>$filename"}> is the line-by-line contents of
  970. $filename for all the compiled files.  Same for C<eval>ed strings which
  971. contain subroutines, or which are currently executed.  The C<$filename>
  972. for C<eval>ed strings looks like C<(eval 34)>.
  973.  
  974. =item *
  975.  
  976. The hash C<%{"_E<lt>$filename"}> contains breakpoints and action (it is
  977. keyed by line number), and individual entries are settable (as opposed
  978. to the whole hash).  Only true/false is important to Perl, though the
  979. values used by F<perl5db.pl> have the form
  980. C<"$break_condition\0$action">.  Values are magical in numeric context:
  981. they are zeros if the line is not breakable.
  982.  
  983. Same for evaluated strings which contain subroutines, or which are
  984. currently executed.  The $filename for C<eval>ed strings looks like
  985. C<(eval 34)>.
  986.  
  987. =item *
  988.  
  989. The scalar C<${"_E<lt>$filename"}> contains C<"_E<lt>$filename">.  Same for
  990. evaluated strings which contain subroutines, or which are currently
  991. executed.  The $filename for C<eval>ed strings looks like C<(eval
  992. 34)>.
  993.  
  994. =item *
  995.  
  996. After each C<require>d file is compiled, but before it is executed,
  997. C<DB::postponed(*{"_E<lt>$filename"})> is called (if subroutine
  998. C<DB::postponed> exists).  Here the $filename is the expanded name of
  999. the C<require>d file (as found in values of %INC).
  1000.  
  1001. =item *
  1002.  
  1003. After each subroutine C<subname> is compiled existence of
  1004. C<$DB::postponed{subname}> is checked.  If this key exists,
  1005. C<DB::postponed(subname)> is called (if subroutine C<DB::postponed>
  1006. exists).
  1007.  
  1008. =item *
  1009.  
  1010. A hash C<%DB::sub> is maintained, with keys being subroutine names,
  1011. values having the form C<filename:startline-endline>.  C<filename> has
  1012. the form C<(eval 31)> for subroutines defined inside C<eval>s.
  1013.  
  1014. =item *
  1015.  
  1016. When execution of the application reaches a place that can have
  1017. a breakpoint, a call to C<DB::DB()> is performed if any one of
  1018. variables $DB::trace, $DB::single, or $DB::signal is true. (Note that
  1019. these variables are not C<local>izable.) This feature is disabled when
  1020. the control is inside C<DB::DB()> or functions called from it (unless
  1021. C<$^D & (1E<lt>E<lt>30)>).
  1022.  
  1023. =item *
  1024.  
  1025. When execution of the application reaches a subroutine call, a call
  1026. to C<&DB::sub>(I<args>) is performed instead, with C<$DB::sub> being
  1027. the name of the called subroutine. (Unless the subroutine is compiled
  1028. in the package C<DB>.)
  1029.  
  1030. =back
  1031.  
  1032. Note that if C<&DB::sub> needs some external data to be setup for it
  1033. to work, no subroutine call is possible until this is done.  For the
  1034. standard debugger C<$DB::deep> (how many levels of recursion deep into
  1035. the debugger you can go before a mandatory break) gives an example of
  1036. such a dependency.
  1037.  
  1038. The minimal working debugger consists of one line
  1039.  
  1040.   sub DB::DB {}
  1041.  
  1042. which is quite handy as contents of C<PERL5DB> environment
  1043. variable:
  1044.  
  1045.   env "PERL5DB=sub DB::DB {}" perl -d your-script
  1046.  
  1047. Another (a little bit more useful) minimal debugger can be created
  1048. with the only line being
  1049.  
  1050.   sub DB::DB {print ++$i; scalar <STDIN>}
  1051.  
  1052. This debugger would print the sequential number of encountered
  1053. statement, and would wait for your C<CR> to continue.
  1054.  
  1055. The following debugger is quite functional:
  1056.  
  1057.   {
  1058.     package DB;
  1059.     sub DB  {}
  1060.     sub sub {print ++$i, " $sub\n"; &$sub}
  1061.   }
  1062.  
  1063. It prints the sequential number of subroutine call and the name of the
  1064. called subroutine.  Note that C<&DB::sub> should be compiled into the
  1065. package C<DB>.
  1066.  
  1067. =head2 Debugger Internals
  1068.  
  1069. At the start, the debugger reads your rc file (F<./.perldb> or
  1070. F<~/.perldb> under Unix), which can set important options.  This file may
  1071. define a subroutine C<&afterinit> to be executed after the debugger is
  1072. initialized.
  1073.  
  1074. After the rc file is read, the debugger reads environment variable
  1075. PERLDB_OPTS and parses it as a rest of C<O ...> line in debugger prompt.
  1076.  
  1077. It also maintains magical internal variables, such as C<@DB::dbline>,
  1078. C<%DB::dbline>, which are aliases for C<@{"::_<current_file"}>
  1079. C<%{"::_<current_file"}>.  Here C<current_file> is the currently
  1080. selected (with the debugger's C<f> command, or by flow of execution)
  1081. file.
  1082.  
  1083. Some functions are provided to simplify customization.  See L<"Debugger
  1084. Customization"> for description of C<DB::parse_options(string)>.  The
  1085. function C<DB::dump_trace(skip[, count])> skips the specified number
  1086. of frames, and returns a list containing info about the caller
  1087. frames (all if C<count> is missing).  Each entry is a hash with keys
  1088. C<context> (C<$> or C<@>), C<sub> (subroutine name, or info about
  1089. eval), C<args> (C<undef> or a reference to an array), C<file>, and
  1090. C<line>.
  1091.  
  1092. The function C<DB::print_trace(FH, skip[, count[, short]])> prints
  1093. formatted info about caller frames.  The last two functions may be
  1094. convenient as arguments to C<E<lt>>, C<E<lt>E<lt>> commands.
  1095.  
  1096. =head2 Other resources
  1097.  
  1098. You did try the B<-w> switch, didn't you?
  1099.  
  1100. =head2 BUGS
  1101.  
  1102. You cannot get the stack frame information or otherwise debug functions
  1103. that were not compiled by Perl, such as C or C++ extensions.
  1104.  
  1105. If you alter your @_ arguments in a subroutine (such as with B<shift>
  1106. or B<pop>, the stack backtrace will not show the original values.
  1107.  
  1108. =head1 Debugging Perl memory usage
  1109.  
  1110. Perl is I<very> frivolous with memory.  There is a saying that to
  1111. estimate memory usage of Perl, assume a reasonable algorithm of
  1112. allocation, and multiply your estimages by 10.  This is not absolutely
  1113. true, but may give you a good grasp of what happens.
  1114.  
  1115. Say, an integer cannot take less than 20 bytes of memory, a float
  1116. cannot take less than 24 bytes, a string cannot take less than 32
  1117. bytes (all these examples assume 32-bit architectures, the result are
  1118. much worse on 64-bit architectures).  If a variable is accessed in two
  1119. of three different ways (which require an integer, a float, or a
  1120. string), the memory footprint may increase by another 20 bytes.  A
  1121. sloppy malloc() implementation will make these numbers yet more.
  1122.  
  1123. On the opposite end of the scale, a declaration like
  1124.  
  1125.   sub foo;
  1126.  
  1127. may take (on some versions of perl) up to 500 bytes of memory.
  1128.  
  1129. Off-the-cuff anecdotal estimates of a code bloat give a factor around
  1130. 8.  This means that the compiled form of reasonable (commented
  1131. indented etc.)  code will take approximately 8 times more than the
  1132. disk space the code takes.
  1133.  
  1134. There are two Perl-specific ways to analyze the memory usage:
  1135. $ENV{PERL_DEBUG_MSTATS} and B<-DL> switch.  First one is available
  1136. only if perl is compiled with Perl's malloc(), the second one only if
  1137. Perl compiled with C<-DDEBUGGING> (as with giving C<-D optimise=-g>
  1138. option to F<Configure>).
  1139.  
  1140. =head2 Using C<$ENV{PERL_DEBUG_MSTATS}>
  1141.  
  1142. If your perl is using Perl's malloc(), and compiled with correct
  1143. switches (this is the default), then it will print memory usage
  1144. statistics after compiling your code (if C<$ENV{PERL_DEBUG_MSTATS}> >
  1145. 1), and before termination of the script (if
  1146. C<$ENV{PERL_DEBUG_MSTATS}> >= 1).  The report format is similar to one
  1147. in the following example:
  1148.  
  1149.   env PERL_DEBUG_MSTATS=2 perl -e "require Carp"
  1150.   Memory allocation statistics after compilation: (buckets 4(4)..8188(8192)
  1151.      14216 free:   130   117    28     7     9   0   2     2   1 0 0
  1152.         437    61    36     0     5
  1153.      60924 used:   125   137   161    55     7   8   6    16   2 0 1
  1154.          74   109   304    84    20
  1155.   Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048.
  1156.   Memory allocation statistics after execution:   (buckets 4(4)..8188(8192)
  1157.      30888 free:   245    78    85    13     6   2   1     3   2 0 1
  1158.         315   162    39    42    11
  1159.     175816 used:   265   176  1112   111    26  22  11    27   2 1 1
  1160.         196   178  1066   798    39
  1161.   Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144.
  1162.  
  1163. It is possible to ask for such a statistic at arbitrary moment by
  1164. usind Devel::Peek::mstats() (module Devel::Peek is available on CPAN).
  1165.  
  1166. Here is the explanation of different parts of the format:
  1167.  
  1168. =over
  1169.  
  1170. =item C<buckets SMALLEST(APPROX)..GREATEST(APPROX)>
  1171.  
  1172. Perl's malloc() uses bucketed allocations.  Every request is rounded
  1173. up to the closest bucket size available, and a bucket of these size is
  1174. taken from the pool of the buckets of this size.
  1175.  
  1176. The above line describes limits of buckets currently in use.  Each
  1177. bucket has two sizes: memory footprint, and the maximal size of user
  1178. data which may be put into this bucket.  Say, in the above example the
  1179. smallest bucket is both sizes 4.  The biggest bucket has usable size
  1180. 8188, and the memory footprint 8192.  
  1181.  
  1182. With debugging Perl some buckets may have negative usable size.  This
  1183. means that these buckets cannot (and will not) be used.  For greater
  1184. buckets the memory footprint may be one page greater than a power of
  1185. 2.  In such a case the corresponding power of two is printed instead
  1186. in the C<APPROX> field above.
  1187.  
  1188. =item Free/Used
  1189.  
  1190. The following 1 or 2 rows of numbers correspond to the number of
  1191. buckets of each size between C<SMALLEST> and C<GREATEST>.  In the
  1192. first row the sizes (memory footprints) of buckets are powers of two
  1193. (or possibly one page greater).  In the second row (if present) the
  1194. memory footprints of the buckets are between memory footprints of two
  1195. buckets "above".  
  1196.  
  1197. Say, with the above example the memory footprints are (with current
  1198. algorith)
  1199.  
  1200.      free:    8     16    32    64    128  256 512 1024 2048 4096 8192
  1201.        4     12    24    48    80
  1202.  
  1203. With non-C<DEBUGGING> perl the buckets starting from C<128>-long ones
  1204. have 4-byte overhead, thus 8192-long bucket may take up to
  1205. 8188-byte-long allocations.
  1206.  
  1207. =item C<Total sbrk(): SBRKed/SBRKs:CONTINUOUS>
  1208.  
  1209. The first two fields give the total amount of memory perl sbrk()ed,
  1210. and number of sbrk()s used.  The third number is what perl thinks
  1211. about continuity of returned chunks.  As far as this number is
  1212. positive, malloc() will assume that it is probable that sbrk() will
  1213. provide continuous memory.
  1214.  
  1215. The amounts sbrk()ed by external libraries is not counted.
  1216.  
  1217. =item C<pad: 0>
  1218.  
  1219. The amount of sbrk()ed memory needed to keep buckets aligned.
  1220.  
  1221. =item C<heads: 2192>
  1222.  
  1223. While memory overhead of bigger buckets is kept inside the bucket, for
  1224. smaller buckets it is kept in separate areas.  This field gives the
  1225. total size of these areas.
  1226.  
  1227. =item C<chain: 0>
  1228.  
  1229. malloc() may want to subdivide a bigger bucket into smaller buckets.
  1230. If only a part of the deceased-bucket is left non-subdivided, the rest
  1231. is kept as an element of a linked list.  This field gives the total
  1232. size of these chunks.
  1233.  
  1234. =item C<tail: 6144>
  1235.  
  1236. To minimize amount of sbrk()s malloc() asks for more memory.  This
  1237. field gives the size of the yet-unused part, which is sbrk()ed, but
  1238. never touched.
  1239.  
  1240. =back
  1241.  
  1242. =head2 Example of using B<-DL> switch
  1243.  
  1244. Below we show how to analyse memory usage by 
  1245.  
  1246.   do 'lib/auto/POSIX/autosplit.ix';
  1247.  
  1248. The file in question contains a header and 146 lines similar to
  1249.  
  1250.   sub getcwd ;
  1251.  
  1252. B<Note:> I<the discussion below supposes 32-bit architecture.  In the
  1253. newer versions of perl the memory usage of the constructs discussed
  1254. here is much improved, but the story discussed below is a real-life
  1255. story.  This story is very terse, and assumes more than cursory
  1256. knowledge of Perl internals.>
  1257.  
  1258. Here is the itemized list of Perl allocations performed during parsing
  1259. of this file:
  1260.  
  1261.  !!! "after" at test.pl line 3.
  1262.     Id  subtot   4   8  12  16  20  24  28  32  36  40  48  56  64  72  80 80+
  1263.   0 02   13752   .   .   .   . 294   .   .   .   .   .   .   .   .   .   .   4
  1264.   0 54    5545   .   .   8 124  16   .   .   .   1   1   .   .   .   .   .   3
  1265.   5 05      32   .   .   .   .   .   .   .   1   .   .   .   .   .   .   .   .
  1266.   6 02    7152   .   .   .   .   .   .   .   .   .   . 149   .   .   .   .   .
  1267.   7 02    3600   .   .   .   .   . 150   .   .   .   .   .   .   .   .   .   .
  1268.   7 03      64   .  -1   .   1   .   .   2   .   .   .   .   .   .   .   .   .
  1269.   7 04    7056   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   7
  1270.   7 17   38404   .   .   .   .   .   .   .   1   .   . 442 149   .   . 147   .
  1271.   9 03    2078  17 249  32   .   .   .   .   2   .   .   .   .   .   .   .   .
  1272.  
  1273.  
  1274. To see this list insert two C<warn('!...')> statements around the call:
  1275.  
  1276.   warn('!');
  1277.   do 'lib/auto/POSIX/autosplit.ix';
  1278.   warn('!!! "after"');
  1279.  
  1280. and run it with B<-DL> option.  The first warn() will print memory
  1281. allocation info before the parsing of the file, and will memorize the
  1282. statistics at this point (we ignore what it prints). The second warn()
  1283. will print increments w.r.t. this memorized statistics.  This is the
  1284. above printout.
  1285.  
  1286. Different I<Id>s on the left correspond to different subsystems of
  1287. perl interpreter, they are just first argument given to perl memory
  1288. allocation API New().  To find what C<9 03> means C<grep> the perl
  1289. source for C<903>.  You will see that it is F<util.c>, function
  1290. savepvn().  This function is used to store a copy of existing chunk of
  1291. memory.  Using C debugger, one can see that it is called either
  1292. directly from gv_init(), or via sv_magic(), and gv_init() is called
  1293. from gv_fetchpv() - which is called from newSUB().
  1294.  
  1295. B<Note:> to reach this place in debugger and skip all the calls to
  1296. savepvn during the compilation of the main script, set a C breakpoint
  1297. in Perl_warn(), C<continue> this point is reached, I<then> set
  1298. breakpoint in Perl_savepvn().  Note that you may need to skip a
  1299. handful of Perl_savepvn() which do not correspond to mass production
  1300. of CVs (there are more C<903> allocations than 146 similar lines of
  1301. F<lib/auto/POSIX/autosplit.ix>).  Note also that C<Perl_> prefixes are
  1302. added by macroization code in perl header files to avoid conflicts
  1303. with external libraries.
  1304.  
  1305. Anyway, we see that C<903> ids correspond to creation of globs, twice
  1306. per glob - for glob name, and glob stringification magic.
  1307.  
  1308. Here are explanations for other I<Id>s above: 
  1309.  
  1310. =over
  1311.  
  1312. =item C<717> 
  1313.  
  1314. is for creation of bigger C<XPV*> structures.  In the above case it
  1315. creates 3 C<AV> per subroutine, one for a list of lexical variable
  1316. names, one for a scratchpad (which contains lexical variables and
  1317. C<targets>), and one for the array of scratchpads needed for
  1318. recursion.  
  1319.  
  1320. It also creates a C<GV> and a C<CV> per subroutine (all called from
  1321. start_subparse()).
  1322.  
  1323. =item C<002>
  1324.  
  1325. Creates C array corresponding to the C<AV> of scratchpads, and the
  1326. scratchpad itself (the first fake entry of this scratchpad is created
  1327. though the subroutine itself is not defined yet).
  1328.  
  1329. It also creates C arrays to keep data for the stash (this is one HV,
  1330. but it grows, thus there are 4 big allocations: the big chunks are not
  1331. freeed, but are kept as additional arenas for C<SV> allocations).
  1332.  
  1333. =item C<054>
  1334.  
  1335. creates a C<HEK> for the name of the glob for the subroutine (this
  1336. name is a key in a I<stash>).
  1337.  
  1338. Big allocations with this I<Id> correspond to allocations of new
  1339. arenas to keep C<HE>.
  1340.  
  1341. =item C<602>
  1342.  
  1343. creates a C<GP> for the glob for the subroutine.
  1344.  
  1345. =item C<702>
  1346.  
  1347. creates the C<MAGIC> for the glob for the subroutine.
  1348.  
  1349. =item C<704>
  1350.  
  1351. creates I<arenas> which keep SVs.
  1352.  
  1353. =back
  1354.  
  1355. =head2 B<-DL> details
  1356.  
  1357. If Perl is run with B<-DL> option, then warn()s which start with `!'
  1358. behave specially.  They print a list of I<categories> of memory
  1359. allocations, and statistics of allocations of different sizes for
  1360. these categories.
  1361.  
  1362. If warn() string starts with
  1363.  
  1364. =over
  1365.  
  1366. =item C<!!!> 
  1367.  
  1368. print changed categories only, print the differences in counts of allocations;
  1369.  
  1370. =item C<!!> 
  1371.  
  1372. print grown categories only; print the absolute values of counts, and totals;
  1373.  
  1374. =item C<!>
  1375.  
  1376. print nonempty categories, print the absolute values of counts and totals.
  1377.  
  1378. =back
  1379.  
  1380. =head2 Limitations of B<-DL> statistic
  1381.  
  1382. If an extension or an external library does not use Perl API to
  1383. allocate memory, these allocations are not counted.
  1384.  
  1385. =head1 Debugging regular expressions
  1386.  
  1387. There are two ways to enable debugging output for regular expressions.
  1388.  
  1389. If your perl is compiled with C<-DDEBUGGING>, you may use the
  1390. B<-Dr> flag on the command line.
  1391.  
  1392. Otherwise, one can C<use re 'debug'>, which has effects both at
  1393. compile time, and at run time (and is I<not> lexically scoped).
  1394.  
  1395. =head2 Compile-time output
  1396.  
  1397. The debugging output for the compile time looks like this:
  1398.  
  1399.   compiling RE `[bc]d(ef*g)+h[ij]k$'
  1400.   size 43 first at 1
  1401.      1: ANYOF(11)
  1402.     11: EXACT <d>(13)
  1403.     13: CURLYX {1,32767}(27)
  1404.     15:   OPEN1(17)
  1405.     17:     EXACT <e>(19)
  1406.     19:     STAR(22)
  1407.     20:       EXACT <f>(0)
  1408.     22:     EXACT <g>(24)
  1409.     24:   CLOSE1(26)
  1410.     26:   WHILEM(0)
  1411.     27: NOTHING(28)
  1412.     28: EXACT <h>(30)
  1413.     30: ANYOF(40)
  1414.     40: EXACT <k>(42)
  1415.     42: EOL(43)
  1416.     43: END(0)
  1417.   anchored `de' at 1 floating `gh' at 3..2147483647 (checking floating)
  1418.                     stclass `ANYOF' minlen 7
  1419.  
  1420. The first line shows the pre-compiled form of the regexp, and the
  1421. second shows the size of the compiled form (in arbitrary units,
  1422. usually 4-byte words) and the label I<id> of the first node which
  1423. does a match.
  1424.  
  1425. The last line (split into two lines in the above) contains the optimizer
  1426. info.  In the example shown, the optimizer found that the match 
  1427. should contain a substring C<de> at the offset 1, and substring C<gh>
  1428. at some offset between 3 and infinity.  Moreover, when checking for
  1429. these substrings (to abandon impossible matches quickly) it will check
  1430. for the substring C<gh> before checking for the substring C<de>.  The
  1431. optimizer may also use the knowledge that the match starts (at the
  1432. C<first> I<id>) with a character class, and the match cannot be
  1433. shorter than 7 chars.
  1434.  
  1435. The fields of interest which may appear in the last line are
  1436.  
  1437. =over
  1438.  
  1439. =item C<anchored> I<STRING> C<at> I<POS>
  1440.  
  1441. =item C<floating> I<STRING> C<at> I<POS1..POS2>
  1442.  
  1443. see above;
  1444.  
  1445. =item C<matching floating/anchored>
  1446.  
  1447. which substring to check first;
  1448.  
  1449. =item C<minlen>
  1450.  
  1451. the minimal length of the match;
  1452.  
  1453. =item C<stclass> I<TYPE>
  1454.  
  1455. The type of the first matching node.
  1456.  
  1457. =item C<noscan>
  1458.  
  1459. which advises to not scan for the found substrings;
  1460.  
  1461. =item C<isall>
  1462.  
  1463. which says that the optimizer info is in fact all that the regular
  1464. expression contains (thus one does not need to enter the RE engine at
  1465. all);
  1466.  
  1467. =item C<GPOS>
  1468.  
  1469. if the pattern contains C<\G>;
  1470.  
  1471. =item C<plus> 
  1472.  
  1473. if the pattern starts with a repeated char (as in C<x+y>);
  1474.  
  1475. =item C<implicit>
  1476.  
  1477. if the pattern starts with C<.*>;
  1478.  
  1479. =item C<with eval> 
  1480.  
  1481. if the pattern contain eval-groups (see L<perlre/(?{ code })>);
  1482.  
  1483. =item C<anchored(TYPE)>
  1484.  
  1485. if the pattern may
  1486. match only at a handful of places  (with C<TYPE> being
  1487. C<BOL>, C<MBOL>, or C<GPOS>, see the table below).
  1488.  
  1489. =back
  1490.  
  1491. If a substring is known to match at end-of-line only, it may be
  1492. followed by C<$>, as in C<floating `k'$>.
  1493.  
  1494. The optimizer-specific info is used to avoid entering (a slow) RE
  1495. engine on strings which will definitely not match.  If C<isall> flag
  1496. is set, a call to the RE engine may be avoided even when optimizer
  1497. found an appropriate place for the match.
  1498.  
  1499. The rest of the output contains the list of I<nodes> of the compiled
  1500. form of the RE.  Each line has format 
  1501.  
  1502. C<   >I<id>: I<TYPE> I<OPTIONAL-INFO> (I<next-id>)
  1503.  
  1504. =head2 Types of nodes
  1505.  
  1506. Here is the list of possible types with short descriptions:
  1507.  
  1508.     # TYPE arg-description [num-args] [longjump-len] DESCRIPTION
  1509.  
  1510.     # Exit points
  1511.     END        no    End of program.
  1512.     SUCCEED    no    Return from a subroutine, basically.
  1513.  
  1514.     # Anchors:
  1515.     BOL        no    Match "" at beginning of line.
  1516.     MBOL    no    Same, assuming multiline.
  1517.     SBOL    no    Same, assuming singleline.
  1518.     EOS        no    Match "" at end of string.
  1519.     EOL        no    Match "" at end of line.
  1520.     MEOL    no    Same, assuming multiline.
  1521.     SEOL    no    Same, assuming singleline.
  1522.     BOUND    no    Match "" at any word boundary
  1523.     BOUNDL    no    Match "" at any word boundary
  1524.     NBOUND    no    Match "" at any word non-boundary
  1525.     NBOUNDL    no    Match "" at any word non-boundary
  1526.     GPOS    no    Matches where last m//g left off.
  1527.  
  1528.     # [Special] alternatives
  1529.     ANY        no    Match any one character (except newline).
  1530.     SANY    no    Match any one character.
  1531.     ANYOF    sv    Match character in (or not in) this class.
  1532.     ALNUM    no    Match any alphanumeric character
  1533.     ALNUML    no    Match any alphanumeric char in locale
  1534.     NALNUM    no    Match any non-alphanumeric character
  1535.     NALNUML    no    Match any non-alphanumeric char in locale
  1536.     SPACE    no    Match any whitespace character
  1537.     SPACEL    no    Match any whitespace char in locale
  1538.     NSPACE    no    Match any non-whitespace character
  1539.     NSPACEL    no    Match any non-whitespace char in locale
  1540.     DIGIT    no    Match any numeric character
  1541.     NDIGIT    no    Match any non-numeric character
  1542.  
  1543.     # BRANCH    The set of branches constituting a single choice are hooked
  1544.     #        together with their "next" pointers, since precedence prevents
  1545.     #        anything being concatenated to any individual branch.  The
  1546.     #        "next" pointer of the last BRANCH in a choice points to the
  1547.     #        thing following the whole choice.  This is also where the
  1548.     #        final "next" pointer of each individual branch points; each
  1549.     #        branch starts with the operand node of a BRANCH node.
  1550.     #
  1551.     BRANCH    node    Match this alternative, or the next...
  1552.  
  1553.     # BACK    Normal "next" pointers all implicitly point forward; BACK
  1554.     #        exists to make loop structures possible.
  1555.     # not used
  1556.     BACK    no    Match "", "next" ptr points backward.
  1557.  
  1558.     # Literals
  1559.     EXACT    sv    Match this string (preceded by length).
  1560.     EXACTF    sv    Match this string, folded (prec. by length).
  1561.     EXACTFL    sv    Match this string, folded in locale (w/len).
  1562.  
  1563.     # Do nothing
  1564.     NOTHING    no    Match empty string.
  1565.     # A variant of above which delimits a group, thus stops optimizations
  1566.     TAIL    no    Match empty string. Can jump here from outside.
  1567.  
  1568.     # STAR,PLUS    '?', and complex '*' and '+', are implemented as circular
  1569.     #        BRANCH structures using BACK.  Simple cases (one character
  1570.     #        per match) are implemented with STAR and PLUS for speed
  1571.     #        and to minimize recursive plunges.
  1572.     #
  1573.     STAR    node    Match this (simple) thing 0 or more times.
  1574.     PLUS    node    Match this (simple) thing 1 or more times.
  1575.  
  1576.     CURLY    sv 2    Match this simple thing {n,m} times.
  1577.     CURLYN    no 2    Match next-after-this simple thing 
  1578.     #            {n,m} times, set parenths.
  1579.     CURLYM    no 2    Match this medium-complex thing {n,m} times.
  1580.     CURLYX    sv 2    Match this complex thing {n,m} times.
  1581.  
  1582.     # This terminator creates a loop structure for CURLYX
  1583.     WHILEM    no    Do curly processing and see if rest matches.
  1584.  
  1585.     # OPEN,CLOSE,GROUPP    ...are numbered at compile time.
  1586.     OPEN    num 1    Mark this point in input as start of #n.
  1587.     CLOSE    num 1    Analogous to OPEN.
  1588.  
  1589.     REF        num 1    Match some already matched string
  1590.     REFF    num 1    Match already matched string, folded
  1591.     REFFL    num 1    Match already matched string, folded in loc.
  1592.  
  1593.     # grouping assertions
  1594.     IFMATCH    off 1 2    Succeeds if the following matches.
  1595.     UNLESSM    off 1 2    Fails if the following matches.
  1596.     SUSPEND    off 1 1    "Independent" sub-RE.
  1597.     IFTHEN    off 1 1    Switch, should be preceeded by switcher .
  1598.     GROUPP    num 1    Whether the group matched.
  1599.  
  1600.     # Support for long RE
  1601.     LONGJMP    off 1 1    Jump far away.
  1602.     BRANCHJ    off 1 1    BRANCH with long offset.
  1603.  
  1604.     # The heavy worker
  1605.     EVAL    evl 1    Execute some Perl code.
  1606.  
  1607.     # Modifiers
  1608.     MINMOD    no    Next operator is not greedy.
  1609.     LOGICAL    no    Next opcode should set the flag only.
  1610.  
  1611.     # This is not used yet
  1612.     RENUM    off 1 1    Group with independently numbered parens.
  1613.  
  1614.     # This is not really a node, but an optimized away piece of a "long" node.
  1615.     # To simplify debugging output, we mark it as if it were a node
  1616.     OPTIMIZED    off    Placeholder for dump.
  1617.  
  1618. =head2 Run-time output
  1619.  
  1620. First of all, when doing a match, one may get no run-time output even
  1621. if debugging is enabled.  this means that the RE engine was never
  1622. entered, all of the job was done by the optimizer.
  1623.  
  1624. If RE engine was entered, the output may look like this:
  1625.  
  1626.   Matching `[bc]d(ef*g)+h[ij]k$' against `abcdefg__gh__'
  1627.     Setting an EVAL scope, savestack=3
  1628.      2 <ab> <cdefg__gh_>    |  1: ANYOF
  1629.      3 <abc> <defg__gh_>    | 11: EXACT <d>
  1630.      4 <abcd> <efg__gh_>    | 13: CURLYX {1,32767}
  1631.      4 <abcd> <efg__gh_>    | 26:   WHILEM
  1632.                 0 out of 1..32767  cc=effff31c
  1633.      4 <abcd> <efg__gh_>    | 15:     OPEN1
  1634.      4 <abcd> <efg__gh_>    | 17:     EXACT <e>
  1635.      5 <abcde> <fg__gh_>    | 19:     STAR
  1636.                  EXACT <f> can match 1 times out of 32767...
  1637.     Setting an EVAL scope, savestack=3
  1638.      6 <bcdef> <g__gh__>    | 22:       EXACT <g>
  1639.      7 <bcdefg> <__gh__>    | 24:       CLOSE1
  1640.      7 <bcdefg> <__gh__>    | 26:       WHILEM
  1641.                     1 out of 1..32767  cc=effff31c
  1642.     Setting an EVAL scope, savestack=12
  1643.      7 <bcdefg> <__gh__>    | 15:         OPEN1
  1644.      7 <bcdefg> <__gh__>    | 17:         EXACT <e>
  1645.        restoring \1 to 4(4)..7
  1646.                     failed, try continuation...
  1647.      7 <bcdefg> <__gh__>    | 27:         NOTHING
  1648.      7 <bcdefg> <__gh__>    | 28:         EXACT <h>
  1649.                     failed...
  1650.                 failed...
  1651.  
  1652. The most significant information in the output is about the particular I<node>
  1653. of the compiled RE which is currently being tested against the target string.
  1654. The format of these lines is
  1655.  
  1656. C<    >I<STRING-OFFSET> <I<PRE-STRING>> <I<POST-STRING>>   |I<ID>:  I<TYPE>
  1657.  
  1658. The I<TYPE> info is indented with respect to the backtracking level.
  1659. Other incidental information appears interspersed within.
  1660.  
  1661. =cut
  1662.